---
slug: /
position: 1
title: Guia Rápido
description: Cliente MySQL para Node.js com foco em performance
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import { PageTitle } from '@site/src/components/PageTitle';

<PageTitle title='MySQL2 | Guia Rápido' />

# MySQL2

{/* <Logo className='logo' width={150} height={150} /> */}

Cliente MySQL para Node.js com foco em performance. Suporta instruções preparadas (_prepared statements_), Codificações _non-utf8_, protocolo de log binário (_binary log protocol_), compressão, SSL e muito mais.

[![NPM Version][npm-image]][npm-url]
[![NPM Downloads][downloads-image]][downloads-url]
[![Node.js Version][node-version-image]][node-version-url]
[![GitHub Workflow Status (with event)][ci-image]][ci-url]
[![Codecov][coverage]][coverage-url]
[![License][license-image]][license-url]

## Instalação

O MySQL2 não tem restrições nativas e pode ser instalado no Linux, Mac OS ou Windows sem qualquer problema.

<Tabs>
  <TabItem value='JavaScript' default>

    ```bash
    npm install --save mysql2
    ```

  </TabItem>
  <TabItem value='TypeScript'>

    ```bash
    npm install --save mysql2
    npm install --save-dev @types/node
    ```

    Para documentação e exemplos usando TypeScript, veja [aqui](/docs/documentation/typescript-examples).

  </TabItem>
</Tabs>

<hr />

### Primeira Consulta (_Query_)

> Para explorar mais exemplos de consulta (queries), visite a seção de exemplos [**Consultas Simples**](/docs/examples/queries/simple-queries) e [**Instruções Preparadas (_Prepared Statements_)**](/docs/examples/queries/prepared-statements).

<Tabs>
  <TabItem value='Promise' default>

```js
// Obtém o cliente
import mysql from 'mysql2/promise';

// Cria a conexão com o Banco de Dados
const connection = await mysql.createConnection({
  host: 'localhost',
  user: 'root',
  database: 'test',
});

// Consulta simples
try {
  const [results, fields] = await connection.query(
    'SELECT * FROM `table` WHERE `name` = "Page" AND `age` > 45'
  );

  console.log(results); // "results" contêm as linhas retornadas pelo servidor
  console.log(fields); // "fields" contêm metadados adicionais sobre os resultados, quando disponíveis
} catch (err) {
  console.log(err);
}

// Utilizando espaços reservados (placeholders)
try {
  const [results] = await connection.query(
    'SELECT * FROM `table` WHERE `name` = ? AND `age` > ?',
    ['Page', 45]
  );

  console.log(results);
} catch (err) {
  console.log(err);
}
```

  </TabItem>
  <TabItem value='Callback'>

```js
// Obtém o cliente
const mysql = require('mysql2');

// Cria a conexão com o Banco de Dados
const connection = mysql.createConnection({
  host: 'localhost',
  user: 'root',
  database: 'test',
});

// Consulta simples
connection.query(
  'SELECT * FROM `table` WHERE `name` = "Page" AND `age` > 45',
  function (err, results, fields) {
    console.log(results); // "results" contêm as linhas retornadas pelo servidor
    console.log(fields); // "fields" contêm metadados adicionais sobre os resultados, quando disponíveis
  }
);

// Utilizando espaços reservados (placeholders)
connection.query(
  'SELECT * FROM `table` WHERE `name` = ? AND `age` > ?',
  ['Page', 45],
  function (err, results) {
    console.log(results);
  }
);
```

  </TabItem>
</Tabs>

<hr />

### Usando Instruções Preparadas (_Prepared Statements_)

Com o MySQL2 você também pode obter Instruções Preparadas (Prepared Statements). Dessa forma o MySQL não precisa preparar um plano para a mesma consulta todas as vezes, resultando em um melhor desempenho. Se você não sabe por que isso é importante, veja essa discussão:

- [Como as instruções preparadas (_prepared statements_) podem proteger contra ataques de injeção SQL](https://stackoverflow.com/questions/8263371/how-can-prepared-statements-protect-from-sql-injection-attacks)

O MySQL2 fornece o método auxiliar `execute` que irá preparar e consultar as declarações (_statements_) SQL. Além disso, você também pode usar os métodos `prepare` e `unprepare` para preparar ou desfazer a preparação de declarações (_statements_) manualmente, se necessário.

> Para explorar mais exemplos de Instruções Preparadas (_Prepared Statements_), visite a seção de exemplos [**Instruções Preparadas (_Prepared Statements_)**](/docs/examples/queries/prepared-statements).

<Tabs>
  <TabItem value='Promise' default>

```js
import mysql from 'mysql2/promise';

try {
  // Cria a conexão com o Banco de Dados
  const connection = await mysql.createConnection({
    host: 'localhost',
    user: 'root',
    database: 'test',
  });

  // "execute" irá chamar internamente a preparação e a consulta (query)
  const [results, fields] = await connection.execute(
    'SELECT * FROM `table` WHERE `name` = ? AND `age` > ?',
    ['Rick C-137', 53]
  );

  console.log(results); // "results" contêm as linhas retornadas pelo servidor
  console.log(fields); // "fields" contêm metadados adicionais sobre os resultados, quando disponíveis
} catch (err) {
  console.log(err);
}
```

  </TabItem>
  <TabItem value='Callback'>

```js
const mysql = require('mysql2');

// Cria a conexão com o Banco de Dados
const connection = mysql.createConnection({
  host: 'localhost',
  user: 'root',
  database: 'test',
});

// "execute" irá chamar internamente a preparação e a consulta (query)
connection.execute(
  'SELECT * FROM `table` WHERE `name` = ? AND `age` > ?',
  ['Rick C-137', 53],
  function (err, results, fields) {
    console.log(results); // "results" contêm as linhas retornadas pelo servidor
    console.log(fields); // "fields" contêm metadados adicionais sobre os resultados, quando disponíveis
  }
);
```

  </TabItem>
</Tabs>

:::tip
Se você executar a mesma declaração novamente, ela será selecionada a partir do LRU Cache, o que economizará tempo de preparação da consulta e proporcionará melhor desempenho.
:::

<hr />

### Usando Conjunto de Conexões (_pools_) {#using-connection-pools}

O conjunto de conexões (_pools_) ajuda a reduzir o tempo gasto na conexão com o servidor MySQL, reutilizando uma conexão anterior e deixando-as abertas ao invés de fechá-las quando você termina de usá-las.

Isto melhora a latência das consultas (_queries_), pois evita toda a sobrecarga associada à criação de uma nova conexão.

> Para explorar mais exemplos de Conjunto de Conexões (_pools_), visite a seção de exemplos [**createPool**](/docs/examples/connections/create-pool).

<Tabs>
  <TabItem value='Promise' default>

```js
import mysql from 'mysql2/promise';

// Cria a conexão (pool). As definições específicadas do "createPool" são as predefinições padrões
const pool = mysql.createPool({
  host: 'localhost',
  user: 'root',
  database: 'test',
  waitForConnections: true,
  connectionLimit: 10,
  maxIdle: 10, // Máximo de conexões inativas; o valor padrão é o mesmo que "connectionLimit"
  idleTimeout: 60000, // Tempo limite das conexões inativas em milissegundos; o valor padrão é "60000"
  queueLimit: 0,
  enableKeepAlive: true,
  keepAliveInitialDelay: 0,
});
```

  </TabItem>
  <TabItem value='Callback'>

```js
const mysql = require('mysql2');

// Cria a conexão (pool). As definições específicadas do "createPool" são as predefinições padrões
const pool = mysql.createPool({
  host: 'localhost',
  user: 'root',
  database: 'test',
  waitForConnections: true,
  connectionLimit: 10,
  maxIdle: 10, // Máximo de conexões inativas; o valor padrão é o mesmo que "connectionLimit"
  idleTimeout: 60000, // Tempo limite das conexões inativas em milissegundos; o valor padrão é "60000"
  queueLimit: 0,
  enableKeepAlive: true,
  keepAliveInitialDelay: 0,
});
```

  </TabItem>
</Tabs>

:::note
O _pool_ não estabelece todas as conexões previamente, mas as cria sob demanda até que o limite de conexões seja atingido.
:::

<hr />

Você pode usar o _pool_ da mesma maneira como em uma conexão (usando `pool.query()` e `pool.execute()`):

<Tabs>
  <TabItem value='Promise' default>

```js
try {
  // Para a inicialização do "pool", veja acima
  const [rows, fields] = await pool.query('SELECT `field` FROM `table`');
  // A conexão é automaticamente liberada quando a consulta (query) é resolvida
} catch (err) {
  console.log(err);
}
```

  </TabItem>
  <TabItem value='Callback'>

```js
// Para a inicialização do "pool", veja acima
pool.query('SELECT `field` FROM `table`', function (err, rows, fields) {
  // A conexão é automaticamente liberada quando a consulta (query) é resolvida
});
```

  </TabItem>
</Tabs>

Alternativamente, também existe a possibilidade de adquirir manualmente uma conexão do pool e liberá-la posteriormente:

<Tabs>
  <TabItem value='Promise' default>

```js
// Para a inicialização do "pool", veja acima
const conn = await pool.getConnection();

// Fazer algo com a conexão
await conn.query(/* ... */);

// Não se esqueça de liberar a conexão quando terminar!
pool.releaseConnection(conn);
```

  </TabItem>
  <TabItem value='Callback'>

```js
// Para a inicialização do "pool", veja acima
pool.getConnection(function (err, conn) {
  // Fazer algo com a conexão
  conn.query(/* ... */);

  // Não se esqueça de liberar a conexão quando terminar!
  pool.releaseConnection(conn);
});
```

  </TabItem>
</Tabs>

- Adicionalmente, você pode liberar a conexão usando o objeto `connection`:

  ```js
  conn.release();
  ```

<hr />

### Usando o _Promise Wrapper_

O MySQL2 também suporta _Promise_ API. O que funciona muito bem com o ES7 _async await_.

```js
import mysql from 'mysql2/promise';

async function main() {
  // Cria a conexão com o Banco de Dados
  const connection = await mysql.createConnection({
    host: 'localhost',
    user: 'root',
    database: 'test',
  });

  // Consulta no Banco de Dados
  const [rows, fields] = await connection.execute(
    'SELECT * FROM `table` WHERE `name` = ? AND `age` > ?',
    ['Morty', 14]
  );
}
```

O MySQL2 usa o objeto _`Promise`_ padrão disponível no escopo. Mas você pode escolher qual implementação de _`Promise`_ deseja usar.

```js
// Obtém o cliente
import mysql from 'mysql2/promise';

// Obtém a implementação de "Promise" (nós usaremos o "bluebird")
import bluebird from 'bluebird';

// Cria a conexão, especificando o "bluebird" como "Promise"
const connection = await mysql.createConnection({
  host: 'localhost',
  user: 'root',
  database: 'test',
  Promise: bluebird,
});

// Consulta no Banco de Dados
const [rows, fields] = await connection.execute(
  'SELECT * FROM `table` WHERE `name` = ? AND `age` > ?',
  ['Morty', 14]
);
```

MySQL2 also exposes a `.promise()` function on Pools, so you can create a promise/non-promise connections from the same pool.

```js
import mysql from 'mysql2';

async function main() {
  // create the pool
  const pool = mysql.createPool({
    host: 'localhost',
    user: 'root',
    database: 'test',
  });

  // now get a Promise wrapped instance of that pool
  const promisePool = pool.promise();

  // query database using promises
  const [rows, fields] = await promisePool.query('SELECT 1');
}
```

O MySQL2 também expõe o método .promise() em _Pools_, então você pode criar conexões "_promise/non-promise_" para o mesmo _pool_.

```js {11}
const mysql = require('mysql2');

// Cria a conexão
const conn = mysql.createConnection({
  host: 'localhost',
  user: 'root',
  database: 'test',
});

conn
  .promise()
  .query('SELECT 1')
  .then(([rows, fields]) => {
    console.log(rows);
  })
  .catch(console.log)
  .then(() => conn.end());
```

<hr />

### Resultados em _Array_

Se você tiver duas colunas com o mesmo nome, pode preferir receber os resultados como um _array_, em vez de um objeto, para evitar conflitos. Isso é uma divergência da biblioteca [Node MySQL][node-mysql].

Por exemplo: `` SELECT 1 AS `foo`, 2 AS `foo` ``.

Você pode habilitar essa configuração tanto no nível de conexão (aplica-se a todas as consultas), quanto no nível de consulta (aplica-se apenas a essa consulta específica).

#### Connection Level

<Tabs>
  <TabItem value='Promise' default>

```js {5}
const conn = await mysql.createConnection({
  host: 'localhost',
  database: 'test',
  user: 'root',
  rowsAsArray: true,
});
```

  </TabItem>
  <TabItem value='Callback'>

```js {5}
const conn = mysql.createConnection({
  host: 'localhost',
  database: 'test',
  user: 'root',
  rowsAsArray: true,
});
```

  </TabItem>
</Tabs>

#### Query Level

<Tabs>
  <TabItem value='Promise' default>

```js {4}
try {
  const [results, fields] = await conn.query({
    sql: 'SELECT 1 AS `foo`, 2 AS `foo`',
    rowsAsArray: true,
  });

  console.log(results); // nessa consulta, "results" contêm um array de arrays ao invés de um array de objetos
  console.log(fields); // "fields" mantêm-se inalterados
} catch (err) {
  console.log(err);
}
```

  </TabItem>
  <TabItem value='Callback'>

```js {4}
conn.query(
  {
    sql: 'SELECT 1 AS `foo`, 2 AS `foo`',
    rowsAsArray: true,
  },
  function (err, results, fields) {
    console.log(results); // nessa consulta, "results" contêm um array de arrays ao invés de um array de objetos
    console.log(fields); // "fields" mantêm-se inalterados
  }
);
```

  </TabItem>
</Tabs>

<hr />

:::tip Obtendo Ajuda
Precisa de ajuda? Faça sua pergunta no [Stack Overflow](https://stackoverflow.com/questions/tagged/mysql2) ou [GitHub](https://github.com/sidorares/node-mysql2/discussions).
Se você encontrou um erro, [registre-o no GitHub](https://github.com/sidorares/node-mysql2/issues).
:::

[npm-image]: https://img.shields.io/npm/v/mysql2.svg
[npm-url]: https://npmjs.org/package/mysql2
[node-version-image]: https://img.shields.io/node/v/mysql2.svg
[node-version-url]: https://nodejs.org/download/
[downloads-image]: https://img.shields.io/npm/dm/mysql2.svg
[downloads-url]: https://npmjs.org/package/mysql2
[license-url]: https://github.com/sidorares/node-mysql2/blob/master/License
[license-image]: https://img.shields.io/npm/l/mysql2.svg?maxAge=2592000
[node-mysql]: https://github.com/mysqljs/mysql
[coverage]: https://img.shields.io/codecov/c/github/sidorares/node-mysql2
[coverage-url]: https://app.codecov.io/github/sidorares/node-mysql2
[ci-url]: https://github.com/sidorares/node-mysql2/actions/workflows/ci-coverage.yml?query=branch%3Amaster
[ci-image]: https://img.shields.io/github/actions/workflow/status/sidorares/node-mysql2/ci-coverage.yml?event=push&style=flat&label=CI&branch=master
